This chapter describes the complete interface of TContainer, the starting point of the Containers Library object hierarchy. All containers are ultimately derived from TContainer, so the topics discussed in this chapter apply to all containers in the library, regardless of how they structure the data, what type of data they work with or where is the data stored.
In this chapter, you will learn how to:
- Insert and delete data in a container
- Use iterative methods for performing an action on all or
some of the items in a container
- Use the Status field of a container
- Use the Error method to handle errors
- Write data-structure independent code
Adding data to a container
Adding data to a container is one of the most common operations that you will perform on a container. Usually, once you create a new container, you need to start adding data to it right away. Or you may find that you need to add new data to a previously created container. TContainer provides a very simple way of doing this: the Insert method.
Insert is a boolean function that will take a pointer parameter, and return True or False depending on the success of the operation. For example, the following code will insert 3000 items into the MyContainer object:
var
Item : Pointer;
MyContainer : TContainer;
begin
for i := 1 to 3000 do
begin
Item := NewItem;
MyContainer^.Insert(Item);
end;
end;
The code in the example above can be used to insert data into any container in the library. Since all containers descend from TContainer, it does not matter if MyContainer is an array, a linked list, a table or even a B+ tree. As long as Item is of the proper data type, the application does not need to know what container is being used to store the data. This also applies to all other methods in the TContainer object.
The process of inserting new data into a container is always the same. First, you need to create the data item that you want to insert. Depending on the type of container you are using, the data item can be dynamically allocated data stored in the heap, or static data stored in a variable or a constant. After the data item is created, all you need to do is call the Insert method of the container you are using.
The following example shows how to insert a static record into a standard array container:
var
MyRec : TMyRec;
MyArray : TStdArray;
begin
MyRec.LastName := 'Smith';
MyRec.FirstName := 'John';
MyArray^.Insert(@MyRec);
end;
What gets stored in a container depends on the type of container that you are using. Some containers will just store the value of the pointer passed as a parameter of the Insert method while some others will copy the actual data item to another location. In the example above, when the record in is inserted into the array, the container will make copy of the data in MyRec and store it in another location in memory. This way, MyRec can be discarded when it is not needed anymore (for example, if MyRec is a variable declared within a routine, it will be automatically "disposed of" when you exit the routine).
For more information on how specific containers work, refer to the chapters included in Part II of this manual.
Deleting data from a container
TContainer provides several ways of deleting data from a container. You can delete individual items or delete all items in a container with just one call to a container method. You can also use methods to dispose of the items after they are deleted from the container.
Deleting individual items
You can delete individual items from a container by using the Delete method. Delete takes a pointer to the item that you want to delete from the container, searches for the item in the container and then deletes it.
MyCollection^.Delete(Item);
MyArray^.Delete(@MyRec);
The way Delete finds the correct item to delete depends on how the container stores the data inserted into it. For example, in containers that store dynamically allocated data and always keep the data in memory (like collections, binary trees and linked lists), Delete compares the value of Item (which is a pointer to the actual item) with the memory address of items in the container. If the value of Item matches the memory address of one item in the container, Delete proceeds to delete the item. However, in containers that do not store dynamically allocated data or that keep portions of the data in a stream, Delete compares the data in Item with items stored in the container, until a match is found.
Delete does not dispose of Item after it has been deleted from the container. Therefore, you should always dispose of Item after you are done working with it. If you want to keep your code data-structure independent, you should always use FreeItem for this purpose, instead of deleting the item directly.
If you need to both delete and dispose of the item, you must use Free instead, which is discussed later in this section.
Deleting all items
Sometimes, you may need to delete all the items in a container at once, instead of deleting items one at a time. This is the purpose of the DeleteAll method. DeleteAll deletes all items in a container, but does not dispose of them. It does not take any parameters.
MyList^.DeleteAll;
You must be careful when using this method since once you delete the items from a container, you cannot access them through the container again. If you do not keep track of the deleted items, you will not be able to dispose of them later resulting in a memory leak.
This method is useful if you want to move the items from one container to another, or if you stored items in a container only for temporary structured access to them and you do not wish to dispose of the items when you dispose of the container. For example, you might want to move the items from one sorted collection to another sorted collection that uses a different key to sort the items. This is how it would be done:
for i := 0 to Pred(MyCollectByID^.Count) do
begin
Item := MyCollectByID^.At(i);
MyCollectByName^.Insert(Item);
end;
MyCollectByID^.DeleteAll;
Dispose(MyCollectByID, Done);
Or you might want to store in a collection pointers to all desktop windows in a Turbo Vision application, for displaying their titles in a listbox:
if Desktop^.Current <> nil then
begin
Curr := PWindow(Desktop^.First);
repeat
MyWinCollection^.Insert(Curr);
Curr := PWindow(Curr^.Next);
until (Curr = PWindow(Desktop^.First));
end;
{ ...do something with the windows... }
MyWinCollection^.DeleteAll;
Dispose(MyWinCollection, Done);
If you need to both delete and dispose of the items, you must use FreeAll instead, which is discussed later in this section.
Deleting and disposing of individual items
You can easily delete individual items in a container and then have the container automatically dispose of them for you. This is what the Free method does. Free takes a pointer to the item that you want to delete, looks for the item in the container and deletes it. After the item is delete, It calls FreeItem to dispose of it. Free is equivalent to:
Delete(Item);
FreeItem(Item);
Deleting and disposing of all items
To delete all items in a container and then have the container dispose of them for you, you must use the FreeAll method. FreeAll is a simple method that does not take any parameters.
MyBTree^.FreeAll;
MyStack^.FreeAll;
The Count field
You can determine the number of elements currently stored in a container by using its Count field. In most containers, Count will be equal to the number of items inserted into the container, minus the number of items deleted from it. The value of Count will not depend on the size allocated for the container. For example, you can allocate enough space for storing 20 items in a collection, but have only 10 stored in it. Count, in this case, would have a value of 10.
However, in containers that have a fixed number of elements (like the standard array containers), Count will always have a fixed value equal to the maximum number of elements that can be stored in the container. For example, if you create an array to store 20 elements, Count will always have a value of 20 whatever the number of elements that you insert or delete from the array.
Iterative methods
Often you will find yourself writing loops to go through all items in a container to display the data or perform some calculation. Other times, you will want to perform an action on only items in the container that satisfy some search criterion. For these purposes, TContainer provides two iterator methods: ForEach and ForEachThat. TContainer also provides two specialized iterator methods that allow you to conditionally delete data in a container: DeleteAllThat and FreeAllThat.
Note Additional iterator methods are implemented in TSequence and TGraph. These methods include the FirstThat, LastThat, NextThat and PrevThat iterators.
The ForEach iterator
ForEach takes a pointer to a far local procedure of type TActionProcedure. The procedure has one parameter, which is a pointer to an item stored in the container. ForEach calls that procedure once for each item in the container, in the order that items appear in the container. The following PrintGlobalReport procedure shows an example of a ForEach iterator.
procedure PrintGlobalReport;
procedure PrintReportItem(Item: PMyObject); far;
begin
with Item do
{...print report item...}
end;
begin
MyBinaryTree^.ForEach(@PrintReport);
end;
For each item in the container the nested procedure PrintReportItem is called. PrintReportItem simply prints the item's information to the screen.
Important! You need to be careful about what sort of procedures and functions you call with iterators. In this example, PrintReportItem must be a procedure -- it cannot be an object's method -- and it must be local to (nested in the same block with) the routine that is calling it. It must also be declared as a far procedure, either with the far directive or with the $F+ compiler directive. Finally, the procedure must take a pointer to a container item as its only parameter.
The ForEachThat iterator
ForEachThat is a specialized type of ForEach iterator that allows you to select the items you want to perform an action on, by using a search criterion. ForEachThat takes two parameters: a pointer to a far local boolean function (of type TTestFunction) that implements the search criterion and a pointer to a far local procedure that will perform an action on items that satisfy the search criterion. For example:
procedure PrintCongratulationNotes;
function IncSales(Item : PEmployee): Boolean; far;
begin
with Item do
IncSales := (CurrSales > OldSales);
end;
procedure PrintNote(Item : PEmployee); far;
begin
with Item do
{... print congratulation note ...}
end;
begin
MyTable^.ForEachThat(@IncSales, @PrintNote);
end;
IncSales is a function that returns True if the item passed as a parameter satisfies the search criterion (in this case, those employees that have increased their sales level). Again notice that IncSales and PrintNote are nested and use the far call model.
Conditionally deleting data
TContainer allows you to conditionally delete and dispose of items in a container, by means of the DeleteAllThat and FreeAllThat iterators. These iterators take one parameter, which is a pointer to a far local boolean function of type TTestFunction.
procedure RetrieveExpired;
function HasExpired(P : PAccount): Boolean; far;
begin
if P^.HasExpired
then begin
ExpiredCollection^.Insert(P);
HasExpired := True;
end
else HasExpired := False;
end;
begin
MyCollection^.DeleteAllThat(@HasExpired);
end;
DeleteAllThat does not dispose of the items deleted. If you need to both delete and dispose of the items, you must use FreeAllThat. For example:
procedure RemoveNonSubscriptors;
function NotSubscribed(P: PClient): Boolean; far;
begin
NotSubscribed := not P^.IsSubscriptor;
end;
begin
MyTable^.FreeAllThat(@NotSubscribed);
end;
When using DeleteAllThat, you must be careful to either dispose of each item deleted or to store it in another container that will keep track of the items deleted. Otherwise, you will not be able to dispose of those items resulting in a memory leak.
The status of a container
Occasionally, when working with containers, an error occurs or the container cannot complete an operation for some particular reason. When this happens, you can determine the reason for this by checking the Status field of a container, which stores the error status of the container. Possible values for this field are:
Status flags are mostly used to mark the end of a loop. For example, the following code will display the data of all items in a sequential container:
with MyContainer^ do
begin
if Status > ctOk { Reset an status flag }
then Status := ctOk;
Item := First(Index);
while Status = ctOk do
begin
DisplayData(Item);
Item := Next(Index);
end;
end;
If an error occurs (Status < 0) or the bottom of the container is reached (Status > 0), then the loop will end.
Handling errors
All errors that occur in a container are handled by the Error method. When an error occurs, the container in which the error occurred will call Error and then abort the operation. Error has two parameters: Code and Info. Code is the numeric code of the error that occurred. The Status field is set to the value passed in the Code parameter. Info is an untyped parameter that can contain any additional information about the error. Its type depends on the kind of error that occurred. For example, if Error is called with a code of ctRange, Info will contain the index value that caused the out of range error.
The default Error method displays an error message if the library was compiled with the cdDebug conditional define (more information about conditional defines can be found in the Bsd.* help files). You can override Error in descendant containers if you wish to handle errors differently or if you want to provide more detailed error messages for a given container.
Error can return any of the following values, which will indicate the calling method how to proceed after the error is handled:
By default, Error returns ctAbort. ctRetry is currently supported only by the file structures, which include the tables, the B trees and the B+ trees.
After an error has occurred in a container, all operations are suspended until Reset is called. This method will reset any container error condition by setting the value of Status to ctOk and calling the Reset method of any stream used by the container.
Important! If you override Error to support ctRetry, you should always call Reset before returning control to the calling routine.
Packing a container
Packing a container is the process of recovering unused resources allocated for the container. For example, when you delete an item from a table, the space used by the item will not be recovered until you pack a container.
Pack removes all nil and deleted items from a container and frees any memory, disk space or other type of data storage media associated with those items. Not all containers fully support this method, however. Containers like the linked lists or the binary trees automatically free unused resources when items are deleted, so the default Pack method in these containers does not perform any operation.
Zap is an additional method that you can use to free all items in a container and then pack the container. Zap is equivalent to calling FreeAll followed by Pack.
Writing data-structure independent code
Writing data-structure independent applications require the consistent use of a particular method in the container's interface: DoneItem. DoneItem is used to insure that data retrieved from any container is appropriately disposed of when it is no longer needed.
Some containers make a copy of the data when it is retrieved from the container (for example, containers that store the data in a stream) while others do not (e.g., containers that store all the data directly in the heap). To make your code independent of the data structures that you are using, you should always call DoneItem after retrieving a data item from a container. DoneItem will determine if the data is just a copy of the source data and decide what to do with it accordingly. If the data item is just a copy made by the container, DoneItem will proceed to dispose of it. Otherwise, DoneItem will do nothing with the data item and simply return control to the calling routine.
The following code can be used to display all the data items stored in any sequential container, regardless of where the container stores the data or how it handles it.
with MyContainer^ do
begin
if Status > ctOk
then Status := ctOk;
Item := First(Index);
while Status = ctOk do
begin
DisplayItem(Item);
DoneItem(Item);
Item := Next(Index);
end;
end;
The call to DoneItem immediately after the item is displayed will ensure that Item is disposed of if it is just a copy of the data or that it is left untouched if it is a pointer to the original data held in memory.
DoneItem is always called immediately after a data item is inserted into a container. Therefore, you should always insert an item into the container after you are done making changes to it, or retrieve it again from the container after inserting it.
Client := New(PClient, Init('Smith', 'John'));
Client^.AccountType := 'Savings';
Client^.PhoneNumber := '(405) 122-2333';
MyStreamArray^.Insert(Client);
The use of DoneItem is only required when writing data-structure independent applications, or when items in a container are stored in a stream. You can choose not to use DoneItem when working with containers that store all the data directly in the heap.
Containers and streams
Except file structures, which always store data in a permanent storage area, all containers can be read and stored from and to a stream, respetively, by means of the standard Load and Store methods. For more information on streams and the Load and Store methods, refer to the chapter "Streams," on your Turbo Vision Programming Guide.
All containers use the GetItem and PutItem methods to read and store individual items from and to a stream, respectively. In most cases, you will not have to worry about these methods since the container you use will already have all the necessary functionality implemented into it. However, you will need to modify these methods if you want to store special types of data that are not currently supported (e.g. record types with pointer fields). Consult the reference guide for additional information on the GetItem and PutItem methods.
